//  Notification.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  Notification类是INotification接口的基础实现。
//  它用于在PureMVC框架中传递通知，实现组件间的解耦通信。
//

#if !defined(__PUREMVC_PATTERNS_OBSERVER_NOTIFICATION_HPP__)
#define __PUREMVC_PATTERNS_OBSERVER_NOTIFICATION_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

#include "../../Interfaces/INotification.hpp"

namespace PureMVC
{
    namespace Patterns
    {
        using Interfaces::INotification;

        /**
         * A base <code>INotification</code> implementation.
         *
         * <P>
         * PureMVC does not rely upon underlying event models such
         * as the one provided with Flash, and ActionScript 3 does
         * not have an inherent event model.</P>
         *
         * <P>
         * The Observer Pattern as implemented within PureMVC exists
         * to support event-driven communication between the
         * application and the actors of the MVC triad.</P>
         *
         * <P>
         * Notifications are not meant to be a replacement for Events
         * in Flex/Flash/Apollo. Generally, <code>IMediator</code> implementors
         * place event listeners on their view components, which they
         * then handle in the usual way. This may lead to the broadcast of <code>Notification</code>s to
         * trigger <code>ICommand</code>s or to communicate with other <code>IMediators</code>. <code>IProxy</code> and <code>ICommand</code>
         * instances communicate with each other and <code>IMediator</code>s
         * by broadcasting <code>INotification</code>s.</P>
         *
         * <P>
         * A key difference between Flash <code>Event</code>s and PureMVC
         * <code>Notification</code>s is that <code>Event</code>s follow the
         * 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy
         * until some parent component handles the <code>Event</code>, while
         * PureMVC <code>Notification</code>s follow a 'Publish/Subscribe'
         * pattern. PureMVC classes need not be related to each other in a
         * parent/child relationship in order to communicate with one another
         * using <code>Notification</code>s.
         *
         * @see Patterns/Observer/Observer.hpp PureMVC::Patterns::Observer
         *
         * 中文注释：
         * INotification接口的基础实现。
         *
         * PureMVC不依赖于底层事件模型（如Flash提供的事件模型），且ActionScript 3没有固有的事件模型。
         *
         * PureMVC中实现的观察者模式用于支持应用程序和MVC三元组角色之间的事件驱动通信。
         *
         * 通知并不意味着要替代Flex/Flash/Apollo中的事件。通常，IMediator实现者会在其视图组件上放置事件监听器，
         * 然后以通常的方式处理它们。这可能导致广播Notification以触发ICommand或与其他IMediator通信。
         * IProxy和ICommand实例通过广播INotification彼此通信并与IMediator通信。
         *
         * Flash Event和PureMVC Notification之间的关键区别在于，Event遵循'责任链'模式，
         * 沿着显示层次结构'冒泡'，直到某个父组件处理Event，而PureMVC Notification遵循'发布/订阅'模式。
         * PureMVC类不需要以父子关系相互关联即可使用Notification相互通信。
         */
        class PUREMVC_API Notification : public virtual INotification
        {
        public:
            /**
             * Copy constructor.
             *
             * 中文注释：
             * 复制构造函数。
             */
            explicit Notification(Notification const& arg);

            /**
             * Constructor.
             *
             * @param name name of the <code>Notification</code> instance. (required)
             * @param body the <code>Notification</code> body. (optional)
             * @param type the type of the <code>Notification</code> (optional)
             *
             * 中文注释：
             * 构造函数。
             *
             * @param name Notification实例的名称。（必需）
             * @param body Notification的主体。（可选）
             * @param type Notification的类型。（可选）
             */
            Notification(std::string const& name, void const* body = NULL, std::string const& type = "");
            
            /**
             * Get the name of the <code>Notification</code> instance.
             *
             * @return the name of the <code>Notification</code> instance.
             *
             * 中文注释：
             * 获取Notification实例的名称。
             *
             * @return Notification实例的名称
             */
            virtual std::string const& getName(void) const;

            /**
             * Set the body of the <code>Notification</code> instance.
             *
             * 中文注释：
             * 设置Notification实例的主体。
             *
             * @param body 要设置的主体对象指针
             */
            virtual void setBody(void const* body);

            /**
             * Get the body of the <code>Notification</code> instance.
             *
             * @return the body object.
             *
             * 中文注释：
             * 获取Notification实例的主体。
             *
             * @return 主体对象指针
             */
            virtual void const* getBody(void) const;

            /**
             * Set the type of the <code>Notification</code> instance.
             *
             * 中文注释：
             * 设置Notification实例的类型。
             *
             * @param type 要设置的类型字符串
             */
            virtual void setType(std::string const& type);

            /**
             * Get the type of the <code>Notification</code> instance.
             *
             * @return the type
             *
             * 中文注释：
             * 获取Notification实例的类型。
             *
             * @return 类型字符串
             */
            virtual std::string const& getType(void) const;

            /**
             * Get the string representation of the <code>Notification</code> instance.
             *
             * @return the string representation of the <code>Notification</code> instance.
             *
             * 中文注释：
             * 获取Notification实例的字符串表示。
             *
             * @return Notification实例的字符串表示
             */
            virtual std::string toString(void) const;
              
            /**
             * Get the string representation of the <code>INotification</code> instance.
             *
             * 中文注释：
             * 获取INotification实例的字符串表示。
             *
             * @param arg 用于存储字符串表示的引用
             */
            virtual void toString(std::string& arg) const;

            /**
             * Copy operator.
             *
             * 中文注释：
             * 复制操作符。
             */
            Notification& operator=(Notification const& arg);

            /**
             * Virtual destructor.
             *
             * 中文注释：
             * 虚析构函数。
             */
            virtual ~Notification(void);
        private:
            // the name of the notification instance
            // 中文注释：通知实例的名称
            std::string _name;
            // the body of the notification instance
            // 中文注释：通知实例的主体
            void const* _body;
            // the type of the notification instance
            // 中文注释：通知实例的类型
            std::string _type;
        };
    }
}

#endif /* __PUREMVC_PATTERNS_OBSERVER_NOTIFICATION_HPP__ */
